<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html lang="en-US">
<head>
<!-- GenHTML revision 25226-->
<meta http-equiv="Content-type" content="text/html; charset=utf-8">
<title>Securing Web Applications - The Java EE 6 Tutorial</title>
<meta name="robots" content="index,follow">
<meta name="robots" content="index,follow">
<meta name="date" content="2011-03-01">
<link rel="stylesheet" type="text/css" href="css/default.css">
<link rel="stylesheet" type="text/css" href="css/ipg.css">
<link rel="stylesheet" type="text/css" href="css/javaeetutorial.css">
</head>

<body>

<table border="0" cellpadding="5" cellspacing="0" width="100%">
<tbody>
   <tr valign="top">
      <td width="400px"><p class="toc level1"><a href="docinfo.html">Document Information</a></p>
<p class="toc level1 tocsp"><a href="gexaf.html">Preface</a></p>
<p class="toc level1 tocsp"><a href="gfirp.html">Part&nbsp;I&nbsp;Introduction</a></p>
<p class="toc level2"><a href="bnaaw.html">1.&nbsp;&nbsp;Overview</a></p>
<p class="toc level2"><a href="gfiud.html">2.&nbsp;&nbsp;Using the Tutorial Examples</a></p>
<p class="toc level1 tocsp"><a href="bnadp.html">Part&nbsp;II&nbsp;The Web Tier</a></p>
<p class="toc level2"><a href="bnadr.html">3.&nbsp;&nbsp;Getting Started with Web Applications</a></p>
<p class="toc level2"><a href="bnaph.html">4.&nbsp;&nbsp;JavaServer Faces Technology</a></p>
<p class="toc level2"><a href="giepx.html">5.&nbsp;&nbsp;Introduction to Facelets</a></p>
<p class="toc level2"><a href="gjddd.html">6.&nbsp;&nbsp;Expression Language</a></p>
<p class="toc level2"><a href="bnaqz.html">7.&nbsp;&nbsp;Using JavaServer Faces Technology in Web Pages</a></p>
<p class="toc level2"><a href="gjcut.html">8.&nbsp;&nbsp;Using Converters, Listeners, and Validators</a></p>
<p class="toc level2"><a href="bnatx.html">9.&nbsp;&nbsp;Developing with JavaServer Faces Technology</a></p>
<p class="toc level2"><a href="gkmaa.html">10.&nbsp;&nbsp;JavaServer Faces Technology Advanced Concepts</a></p>
<p class="toc level2"><a href="bnawo.html">11.&nbsp;&nbsp;Configuring JavaServer Faces Applications</a></p>
<p class="toc level2"><a href="gkiow.html">12.&nbsp;&nbsp;Using Ajax with JavaServer Faces Technology</a></p>
<p class="toc level2"><a href="gkhxa.html">13.&nbsp;&nbsp;Advanced Composite Components</a></p>
<p class="toc level2"><a href="bnavg.html">14.&nbsp;&nbsp;Creating Custom UI Components</a></p>
<p class="toc level2"><a href="bnafd.html">15.&nbsp;&nbsp;Java Servlet Technology</a></p>
<p class="toc level2"><a href="bnaxu.html">16.&nbsp;&nbsp;Internationalizing and Localizing Web Applications</a></p>
<p class="toc level1 tocsp"><a href="bnayk.html">Part&nbsp;III&nbsp;Web Services</a></p>
<p class="toc level2"><a href="gijti.html">17.&nbsp;&nbsp;Introduction to Web Services</a></p>
<p class="toc level2"><a href="bnayl.html">18.&nbsp;&nbsp;Building Web Services with JAX-WS</a></p>
<p class="toc level2"><a href="giepu.html">19.&nbsp;&nbsp;Building RESTful Web Services with JAX-RS</a></p>
<p class="toc level2"><a href="gjjxe.html">20.&nbsp;&nbsp;Advanced JAX-RS Features</a></p>
<p class="toc level2"><a href="gkojl.html">21.&nbsp;&nbsp;Running the Advanced JAX-RS Example Application</a></p>
<p class="toc level1 tocsp"><a href="bnblr.html">Part&nbsp;IV&nbsp;Enterprise Beans</a></p>
<p class="toc level2"><a href="gijsz.html">22.&nbsp;&nbsp;Enterprise Beans</a></p>
<p class="toc level2"><a href="gijre.html">23.&nbsp;&nbsp;Getting Started with Enterprise Beans</a></p>
<p class="toc level2"><a href="gijrb.html">24.&nbsp;&nbsp;Running the Enterprise Bean Examples</a></p>
<p class="toc level2"><a href="bnbpk.html">25.&nbsp;&nbsp;A Message-Driven Bean Example</a></p>
<p class="toc level2"><a href="gkcqz.html">26.&nbsp;&nbsp;Using the Embedded Enterprise Bean Container</a></p>
<p class="toc level2"><a href="gkidz.html">27.&nbsp;&nbsp;Using Asynchronous Method Invocation in Session Beans</a></p>
<p class="toc level1 tocsp"><a href="gjbnr.html">Part&nbsp;V&nbsp;Contexts and Dependency Injection for the Java EE Platform</a></p>
<p class="toc level2"><a href="giwhb.html">28.&nbsp;&nbsp;Introduction to Contexts and Dependency Injection for the Java EE Platform</a></p>
<p class="toc level2"><a href="gjbls.html">29.&nbsp;&nbsp;Running the Basic Contexts and Dependency Injection Examples</a></p>
<p class="toc level2"><a href="gjehi.html">30.&nbsp;&nbsp;Contexts and Dependency Injection for the Java EE Platform: Advanced Topics</a></p>
<p class="toc level2"><a href="gkhre.html">31.&nbsp;&nbsp;Running the Advanced Contexts and Dependency Injection Examples</a></p>
<p class="toc level1 tocsp"><a href="bnbpy.html">Part&nbsp;VI&nbsp;Persistence</a></p>
<p class="toc level2"><a href="bnbpz.html">32.&nbsp;&nbsp;Introduction to the Java Persistence API</a></p>
<p class="toc level2"><a href="gijst.html">33.&nbsp;&nbsp;Running the Persistence Examples</a></p>
<p class="toc level2"><a href="bnbtg.html">34.&nbsp;&nbsp;The Java Persistence Query Language</a></p>
<p class="toc level2"><a href="gjitv.html">35.&nbsp;&nbsp;Using the Criteria API to Create Queries</a></p>
<p class="toc level2"><a href="gkjiq.html">36.&nbsp;&nbsp;Creating and Using String-Based Criteria Queries</a></p>
<p class="toc level2"><a href="gkjjf.html">37.&nbsp;&nbsp;Controlling Concurrent Access to Entity Data with Locking</a></p>
<p class="toc level2"><a href="gkjia.html">38.&nbsp;&nbsp;Improving the Performance of Java Persistence API Applications By Setting a Second-Level Cache</a></p>
<p class="toc level1 tocsp"><a href="gijrp.html">Part&nbsp;VII&nbsp;Security</a></p>
<p class="toc level2"><a href="bnbwj.html">39.&nbsp;&nbsp;Introduction to Security in the Java EE Platform</a></p>
<p class="toc level2"><a href="bncas.html">40.&nbsp;&nbsp;Getting Started Securing Web Applications</a></p>
<p class="toc level3"><a href="bncat.html">Overview of Web Application Security</a></p>
<div id="scrolltoc" class="onpage">
<p class="toc level3"><a href="">Securing Web Applications</a></p>
<p class="toc level4"><a href="#bncbk">Specifying Security Constraints</a></p>
<p class="toc level5"><a href="#gjjcd">Specifying a Web Resource Collection</a></p>
<p class="toc level5"><a href="#gjjcg">Specifying an Authorization Constraint</a></p>
<p class="toc level5"><a href="#bncbm">Specifying a Secure Connection</a></p>
<p class="toc level5"><a href="#bncbl">Specifying Separate Security Constraints for Various Resources</a></p>
<p class="toc level4 tocsp"><a href="#gkbsa">Specifying Authentication Mechanisms</a></p>
<p class="toc level5"><a href="#bncbo">HTTP Basic Authentication</a></p>
<p class="toc level5"><a href="#bncbq">Form-Based Authentication</a></p>
<p class="toc level5"><a href="#bncbw">Digest Authentication</a></p>
<p class="toc level5"><a href="#bncbs">Client Authentication</a></p>
<p class="toc level5"><a href="#bncbt">Mutual Authentication</a></p>
<p class="toc level5"><a href="#bncbn">Specifying an Authentication Mechanism in the Deployment Descriptor</a></p>
<p class="toc level4 tocsp"><a href="#bncav">Declaring Security Roles</a></p>
</div>
<p class="toc level3 tocsp"><a href="gjiie.html">Using Programmatic Security with Web Applications</a></p>
<p class="toc level4"><a href="gjiie.html#gircj">Authenticating Users Programmatically</a></p>
<p class="toc level4"><a href="gjiie.html#bncba">Checking Caller Identity Programmatically</a></p>
<p class="toc level4"><a href="gjiie.html#gjjlq">Example Code for Programmatic Security</a></p>
<p class="toc level4"><a href="gjiie.html#bncbb">Declaring and Linking Role References</a></p>
<p class="toc level3 tocsp"><a href="bncbx.html">Examples: Securing Web Applications</a></p>
<p class="toc level4"><a href="bncbx.html#gjjlk">To Set Up Your System for Running the Security Examples</a></p>
<p class="toc level4"><a href="bncbx.html#bncck">Example: Basic Authentication with a Servlet</a></p>
<p class="toc level5"><a href="bncbx.html#gjrmh">Specifying Security for Basic Authentication Using Annotations</a></p>
<p class="toc level5"><a href="bncbx.html#gjqys">To Build, Package, and Deploy the Servlet Basic Authentication Example Using NetBeans IDE</a></p>
<p class="toc level5"><a href="bncbx.html#gjqzh">To Build, Package, and Deploy the Servlet Basic Authentication Example Using Ant</a></p>
<p class="toc level5"><a href="bncbx.html#gjqzf">To Run the Basic Authentication Servlet</a></p>
<p class="toc level4 tocsp"><a href="bncbx.html#bncby">Example: Form-Based Authentication with a JavaServer Faces Application</a></p>
<p class="toc level5"><a href="bncbx.html#bncca">Creating the Login Form and the Error Page</a></p>
<p class="toc level5"><a href="bncbx.html#bnccb">Specifying Security for the Form-Based Authentication Example</a></p>
<p class="toc level5"><a href="bncbx.html#gjrba">To Build, Package, and Deploy the Form-Based Authentication Example Using NetBeans IDE</a></p>
<p class="toc level5"><a href="bncbx.html#gjraz">To Build, Package, and Deploy the Form-Based Authentication Example Using Ant</a></p>
<p class="toc level5"><a href="bncbx.html#gjral">To Run the Form-Based Authentication Example</a></p>
<p class="toc level2 tocsp"><a href="bnbyk.html">41.&nbsp;&nbsp;Getting Started Securing Enterprise Applications</a></p>
<p class="toc level1 tocsp"><a href="gijue.html">Part&nbsp;VIII&nbsp;Java EE Supporting Technologies</a></p>
<p class="toc level2"><a href="gijto.html">42.&nbsp;&nbsp;Introduction to Java EE Supporting Technologies</a></p>
<p class="toc level2"><a href="bncih.html">43.&nbsp;&nbsp;Transactions</a></p>
<p class="toc level2"><a href="bncjh.html">44.&nbsp;&nbsp;Resource Connections</a></p>
<p class="toc level2"><a href="bncdq.html">45.&nbsp;&nbsp;Java Message Service Concepts</a></p>
<p class="toc level2"><a href="bncgv.html">46.&nbsp;&nbsp;Java Message Service Examples</a></p>
<p class="toc level2"><a href="gkahp.html">47.&nbsp;&nbsp;Advanced Bean Validation Concepts and Examples</a></p>
<p class="toc level2"><a href="gkeed.html">48.&nbsp;&nbsp;Using Java EE Interceptors</a></p>
<p class="toc level1 tocsp"><a href="gkgjw.html">Part&nbsp;IX&nbsp;Case Studies</a></p>
<p class="toc level2"><a href="gkaee.html">49.&nbsp;&nbsp;Duke's Tutoring Case Study Example</a></p>
<p class="toc level1 tocsp"><a href="idx-1.html">Index</a></p>
</td>
      <td width="10px">&nbsp;</td>
      <td>
         <div class="header">
             <div class="banner">
                <table width="100%" border="0" cellpadding="5" cellspacing="0">
                   <tbody>
                      <tr>
                         <td valign="bottom"><p class="Banner">The Java EE 6 Tutorial
</p></td>
                         <td align="right"  valign="bottom"><img src="graphics/javalogo.png" alt="Java Coffee Cup logo"></td>
                      </tr>
                   </tbody>
                </table>
             </div>

             <div class="header-links">
	         <a href="./index.html">Home</a> | 
<a href="../information/download.html">Download</a> | 
<a href="./javaeetutorial6.pdf">PDF</a> | 
<a href="../information/faq.html">FAQ</a> | 
<a href="http://download.oracle.com/javaee/feedback.htm">Feedback</a>

             </div>
             <div class="navigation">
                 <a href="bncat.html"><img src="graphics/leftButton.gif" border="0" alt="Previous" title="Previous"></a>
                 <a href="p1.html"><img src="graphics/upButton.gif" border="0" alt="Contents" title="Contents"></a>
                 <a href="gjiie.html"><img src="graphics/rightButton.gif" border="0" alt="Next" title="Next"></a>
             </div>
         </div>

	 <div class="maincontent">      	 
             

<a name="gkbaa"></a><h2>Securing Web Applications</h2>
<p>Web applications are created by application developers who give, sell, or otherwise transfer
the application to an application deployer for installation into a runtime environment. Application
developers communicate how to set up security for the deployed application by using
annotations or deployment descriptors. This information is passed on to the deployer, who
uses it to define method permissions for security roles, set up user authentication, and
set up the appropriate transport mechanism. If the application developer doesn&rsquo;t define security
requirements, the deployer will have to determine the security requirements independently.</p>

<p>Some elements necessary for security in a web application cannot be specified as
annotations for all types of web applications. This chapter explains how to secure
web applications using annotations wherever possible. It explains how to use deployment descriptors
where annotations cannot be used.</p>



<a name="bncbk"></a><h3>Specifying Security Constraints</h3>
<a name="indexterm-2036"></a><a name="indexterm-2037"></a><p>A <b>security constraint</b> is used to define the access privileges to a collection of
resources using their URL mapping.</p>

<p><a name="indexterm-2038"></a><a name="indexterm-2039"></a><a name="indexterm-2040"></a>If your web application uses a servlet, you can express the security constraint
information by using annotations. Specifically, you use the <tt>@HttpConstraint</tt> and, optionally, the <tt>@HttpMethodConstraint</tt>
annotations within the <tt>@ServletSecurity</tt> annotation to specify a security constraint.</p>

<p>If your web application does not use a servlet, however, you must
specify a <tt>security-constraint</tt> element in the deployment descriptor file. The authentication mechanism cannot be
expressed using annotations, so if you use any authentication method other than <tt>BASIC</tt>
(the default), a deployment descriptor is required.</p>

<p>The following subelements can be part of a <tt>security-constraint</tt>:</p>


<ul><li><p><a name="indexterm-2041"></a><b>Web resource collection</b> (<tt>web-resource-collection</tt>): A list of URL patterns (the part of a URL <b>after</b> the host name and port you want to constrain) and HTTP operations (the methods within the files that match the URL pattern you want to constrain) that describe a set of resources to be protected. Web resource collections are discussed in <a href="#gjjcd">Specifying a Web Resource Collection</a>.</p>

</li>
<li><p><a name="indexterm-2042"></a><b>Authorization constraint</b> (<tt>auth-constraint</tt>): Specifies whether authentication is to be used and names the roles authorized to perform the constrained requests. For more information about authorization constraints, see <a href="#gjjcg">Specifying an Authorization Constraint</a>.</p>

</li>
<li><p><a name="indexterm-2043"></a><b>User data constraint</b> (<tt>user-data-constraint</tt>): Specifies how data is protected when transported between a client and a server. User data constraints are discussed in <a href="#bncbm">Specifying a Secure Connection</a>.</p>

</li></ul>


<a name="gjjcd"></a><h4>Specifying a Web Resource Collection</h4>
<a name="indexterm-2044"></a><a name="indexterm-2045"></a><p>A web resource collection consists of the following subelements:</p>


<ul><li><p><tt>web-resource-name</tt> is the name you use for this resource. Its use is optional.</p>

</li>
<li><p><a name="indexterm-2046"></a><tt>url-pattern</tt> is used to list the request URI to be protected. Many applications have both unprotected and protected resources. To provide unrestricted access to a resource, do not configure a security constraint for that particular request URI.</p>

<p>The request URI is the part of a URL <b>after</b> the host name and port. For example, let&rsquo;s say that you have an e-commerce site with a catalog that you would want anyone to be able to access and browse, and a shopping cart area for customers only. You could set up the paths for your web application so that the pattern <tt>/cart/*</tt> is protected but nothing else is protected. Assuming that the application is installed at context path <tt>/myapp</tt>, the following are true:</p>


<ul><li><p><tt>http://localhost:8080/myapp/index.xhtml</tt> is <b>not</b> protected.</p>

</li>
<li><p><tt>http://localhost:8080/myapp/cart/index.xhtml</tt> <b>is</b> protected.</p>

</li></ul>
<p>A user will be prompted to log in the first time he or she accesses a resource in the <tt>cart/</tt> subdirectory.</p>

</li>
<li><p><tt>http-method</tt> or <tt>http-method-omission</tt> is used to specify which methods should be protected or which methods should be omitted from protection. An HTTP method is protected by a <tt>web-resource-collection</tt> under any of the following circumstances:</p>


<ul><li><p>If no HTTP methods are named in the collection (which means that all are protected)</p>

</li>
<li><p>If the collection specifically names the HTTP method in an <tt>http-method</tt> subelement</p>

</li>
<li><p>If the collection contains one or more <tt>http-method-omission</tt> elements, none of which names the HTTP method</p>

</li></ul>
</li></ul>


<a name="gjjcg"></a><h4>Specifying an Authorization Constraint</h4>
<a name="indexterm-2047"></a><a name="indexterm-2048"></a><p>An authorization constraint (<tt>auth-constraint</tt>) contains the <tt>role-name</tt> element. You can use as many
<tt>role-name</tt> elements as needed here.</p>

<p>An authorization constraint establishes a requirement for authentication and names the roles authorized
to access the URL patterns and HTTP methods declared by this security constraint.
If there is no authorization constraint, the container must accept the request without
requiring user authentication. If there is an authorization constraint but no roles are
specified within it, the container will not allow access to constrained requests under
any circumstances. Each role name specified here must either correspond to the role name
of one of the <tt>security-role</tt> elements defined for this web application or be
the specially reserved role name <tt>*</tt>, which indicates all roles in the web
application. Role names are case sensitive. The roles defined for the application must
be mapped to users and groups defined on the server, except when default
principal-to-role mapping is used. </p>

<p>For more information about security roles, see <a href="#bncav">Declaring Security Roles</a>. For information on mapping
security roles, see <a href="bnbxj.html#bnbxv">Mapping Roles to Users and Groups</a>.</p>

<p>For a servlet, the <tt>@HttpConstraint</tt> and <tt>@HttpMethodConstraint</tt> annotations accept a <tt>rolesAllowed</tt> element
that specifies the authorized roles.</p>



<a name="bncbm"></a><h4>Specifying a Secure Connection</h4>
<a name="indexterm-2049"></a><a name="indexterm-2050"></a><a name="indexterm-2051"></a><a name="indexterm-2052"></a><a name="indexterm-2053"></a><a name="indexterm-2054"></a><p>A user data constraint (<tt>user-data-constraint</tt> in the deployment descriptor) contains the <tt>transport-guarantee</tt> subelement. A
user data constraint can be used to require that a protected transport-layer connection,
such as HTTPS, be used for all constrained URL patterns and HTTP methods
specified in the security constraint. The choices for transport guarantee are <tt>CONFIDENTIAL</tt>, <tt>INTEGRAL</tt>,
or <tt>NONE</tt>. If you specify <tt>CONFIDENTIAL</tt> or <tt>INTEGRAL</tt> as a security constraint, it
generally means that the use of SSL is required and applies to all
requests that match the URL patterns in the web resource collection, not just
to the login dialog box.</p>

<p>The strength of the required protection is defined by the value of
the transport guarantee.</p>


<ul><li><p>Specify <tt>CONFIDENTIAL</tt> when the application requires that data be transmitted so as to prevent other entities from observing the contents of the transmission.</p>

</li>
<li><p>Specify <tt>INTEGRAL</tt> when the application requires that the data be sent between client and server in such a way that it cannot be changed in transit.</p>

</li>
<li><p>Specify <tt>NONE</tt> to indicate that the container must accept the constrained requests on any connection, including an unprotected one.</p>

</li></ul>

<hr><p><b>Note - </b>In practice, Java EE servers treat the <tt>CONFIDENTIAL</tt> and <tt>INTEGRAL</tt> transport guarantee
values identically.</p>


<hr>
<p>The user data constraint is handy to use in conjunction with basic
and form-based user authentication. When the login authentication method is set to <tt>BASIC</tt> or
<tt>FORM</tt>, passwords are not protected, meaning that passwords sent between a client and
a server on an unprotected session can be viewed and intercepted by third
parties. Using a user data constraint with the user authentication mechanism can alleviate this
concern. Configuring a user authentication mechanism is described in <a href="#bncbn">Specifying an Authentication Mechanism in the Deployment Descriptor</a>.</p>

<p>To guarantee that data is transported over a secure connection, ensure that SSL
support is configured for your server. SSL support is already configured for the
GlassFish Server.</p>


<hr><p><b>Note - </b>After you switch to SSL for a session, you should never accept any
non-SSL requests for the rest of that session. For example, a shopping site
might not use SSL until the checkout page, and then it might
switch to using SSL to accept your card number. After switching to SSL,
you should stop listening to non-SSL requests for this session. The reason for
this practice is that the session ID itself was not encrypted on the
earlier communications. This is not so bad when you&rsquo;re only doing your shopping,
but after the credit card information is stored in the session, you don&rsquo;t
want anyone to use that information to fake the purchase transaction against your
credit card. This practice could be easily implemented by using a filter.</p>


<hr>


<a name="bncbl"></a><h4>Specifying Separate Security Constraints for Various Resources</h4>
<a name="indexterm-2055"></a><p>You can create a separate security constraint for various resources within your application.
For example, you could allow users with the role of <tt>PARTNER</tt> access to
the <tt>GET</tt> and <tt>POST</tt> methods of all resources with the URL pattern
<tt>/acme/wholesale/*</tt> and allow users with the role of <tt>CLIENT</tt> access to the <tt>GET</tt>
and <tt>POST</tt> methods of all resources with the URL pattern <tt>/acme/retail/*</tt>. An example
of a deployment descriptor that would demonstrate this functionality is the following:</p>

<pre><b>&lt;!-- SECURITY CONSTRAINT #1 --></b>
&lt;security-constraint>
    &lt;web-resource-collection>
        &lt;web-resource-name>wholesale&lt;/web-resource-name>
        &lt;url-pattern>/acme/wholesale/*&lt;/url-pattern>
        &lt;http-method>GET&lt;/http-method>
        &lt;http-method>POST&lt;/http-method>
    &lt;/web-resource-collection>
    &lt;auth-constraint>
        &lt;role-name>PARTNER&lt;/role-name>
    &lt;/auth-constraint>
    &lt;user-data-constraint>
        &lt;transport-guarantee>CONFIDENTIAL&lt;/transport-guarantee>
    &lt;/user-data-constraint>
&lt;/security-constraint>

<b>&lt;!-- SECURITY CONSTRAINT #2 --></b>
&lt;security-constraint>
    &lt;web-resource-collection>
        &lt;web-resource-name>retail&lt;/web-resource-name>
        &lt;url-pattern>/acme/retail/*&lt;/url-pattern>
        &lt;http-method>GET&lt;/http-method>
        &lt;http-method>POST&lt;/http-method>
    &lt;/web-resource-collection>
    &lt;auth-constraint>
        &lt;role-name>CLIENT&lt;/role-name>
    &lt;/auth-constraint>
    &lt;user-data-constraint>
        &lt;transport-guarantee>CONFIDENTIAL&lt;/transport-guarantee>
    &lt;/user-data-constraint>
&lt;/security-constraint></pre><p>When the same <tt>url-pattern</tt> and <tt>http-method</tt> occur in multiple security constraints, the constraints
on the pattern and method are defined by combining the individual constraints, which
could result in unintentional denial of access.</p>



<a name="gkbsa"></a><h3>Specifying Authentication Mechanisms</h3>
<a name="indexterm-2056"></a><a name="indexterm-2057"></a><p>A user authentication mechanism specifies</p>


<ul><li><p>The way a user gains access to web content</p>

</li>
<li><p>With basic authentication, the realm in which the user will be authenticated</p>

</li>
<li><p>With form-based authentication, additional attributes</p>

</li></ul>
<p>When an authentication mechanism is specified, the user must be authenticated before access
is granted to any resource that is constrained by a security constraint. There
can be multiple security constraints applying to multiple resources, but the same authentication
method will apply to all constrained resources in an application.</p>

<p>Before you can authenticate a user, you must have a database of
user names, passwords, and roles configured on your web or application server. For information
on setting up the user database, see <a href="bnbxj.html#bnbxr">Managing Users and Groups on the GlassFish Server</a>.</p>

<p>HTTP basic authentication and form-based authentication are not very secure authentication mechanisms. Basic
authentication sends user names and passwords over the Internet as Base64-encoded text; form-based
authentication sends this data as plain text. In both cases, the target server
is not authenticated. Therefore, these forms of authentication leave user data exposed and
vulnerable. If someone can intercept the transmission, the user name and password information can
easily be decoded. However, when a secure transport mechanism, such as SSL, or
security at the network level, such as the Internet Protocol Security (IPsec) protocol
or virtual private network (VPN) strategies, is used in conjunction with basic or
form-based authentication, some of these concerns can be alleviated. To specify a secure
transport mechanism, use the elements described in <a href="#bncbm">Specifying a Secure Connection</a>.</p>



<a name="bncbo"></a><h4>HTTP Basic Authentication</h4>
<a name="indexterm-2058"></a><a name="indexterm-2059"></a><a name="indexterm-2060"></a><p>Specifying <b>HTTP basic authentication</b> requires that the server request a user name and password from
the web client and verify that the user name and password are valid
by comparing them against a database of authorized users in the specified or
default realm.</p>

<p>Basic authentication is the default when you do not specify an authentication mechanism.</p>

<p>When basic authentication is used, the following actions occur:</p>


<ol><li><p>A client requests access to a protected resource.</p>

</li>
<li><p>The web server returns a dialog box that requests the user name and password.</p>

</li>
<li><p>The client submits the user name and password to the server.</p>

</li>
<li><p>The server authenticates the user in the specified realm and, if successful, returns the requested resource.</p>

</li></ol>
<p><a href="#bncbp">Figure&nbsp;40-2</a> shows what happens when you specify HTTP basic authentication.</p>

<a name="bncbp"></a><p class="caption">Figure&nbsp;40-2 HTTP Basic Authentication</p><img src="figures/security-httpBasicAuthentication.gif" alt="Diagram of four steps in HTTP basic authentication between client and server"></img>

<a name="bncbq"></a><h4>Form-Based Authentication</h4>
<a name="indexterm-2061"></a><a name="indexterm-2062"></a><p><b>Form-based authentication</b> allows the developer to control the look and feel of the login
authentication screens by customizing the login screen and error pages that an HTTP
browser presents to the end user. When form-based authentication is declared, the following
actions occur.</p>


<ol><li><p>A client requests access to a protected resource.</p>

</li>
<li><p>If the client is unauthenticated, the server redirects the client to a login page.</p>

</li>
<li><p>The client submits the login form to the server.</p>

</li>
<li><p>The server attempts to authenticate the user.</p>


<ol style="list-style-type: lower-alpha"><li><p>If authentication succeeds, the authenticated user&rsquo;s principal is checked to ensure that it is in a role that is authorized to access the resource. If the user is authorized, the server redirects the client to the resource by using the stored URL path.</p>

</li>
<li><p>If authentication fails, the client is forwarded or redirected to an error page.</p>

</li></ol>
</li></ol>
<p><a href="#gexfa">Figure&nbsp;40-3</a> shows what happens when you specify form-based authentication.</p>

<a name="gexfa"></a><p class="caption">Figure&nbsp;40-3 Form-Based Authentication</p><img src="figures/security-formBasedLogin.gif" alt="Diagram of four steps in form-based authentication between client and server"></img><p>The section <a href="bncbx.html#bncby">Example: Form-Based Authentication with a JavaServer Faces Application</a> is an example application that uses form-based authentication.</p>

<p>When you create a form-based login, be sure to maintain sessions using cookies
or SSL session information.</p>

<p>For authentication to proceed appropriately, the action of the login form must always
be <tt>j_security_check</tt>. This restriction is made so that the login form will work
no matter which resource it is for and to avoid requiring the server
to specify the action field of the outbound form. The following code snippet
shows how the form should be coded into the HTML page:</p>

<pre>&lt;form method="POST" action="j_security_check">
&lt;input type="text" name="j_username">
&lt;input type="password" name="j_password">
&lt;/form></pre>

<a name="bncbw"></a><h4>Digest Authentication</h4>
<a name="indexterm-2063"></a><a name="indexterm-2064"></a><p>Like basic authentication, <b>digest authentication</b> authenticates a user based on a user name and
a password. However, unlike basic authentication, digest authentication does not send user passwords
over the network. Instead, the client sends a one-way cryptographic hash of the
password and additional data. Although passwords are not sent on the wire, digest
authentication requires that clear-text password equivalents be available to the authenticating container so that
it can validate received authenticators by calculating the expected digest.</p>



<a name="bncbs"></a><h4>Client Authentication</h4>
<a name="indexterm-2065"></a><a name="indexterm-2066"></a><a name="indexterm-2067"></a><a name="indexterm-2068"></a><a name="indexterm-2069"></a><a name="indexterm-2070"></a><a name="indexterm-2071"></a><a name="indexterm-2072"></a><p>With <b>client authentication</b>, the web server authenticates the client by using the client&rsquo;s public
key certificate. Client authentication is a more secure method of authentication than either
basic or form-based authentication. It uses HTTP over SSL (HTTPS), in which the
server authenticates the client using the client&rsquo;s public key certificate. SSL technology provides data
encryption, server authentication, message integrity, and optional client authentication for a TCP/IP connection.
You can think of a public key certificate as the digital equivalent of
a passport. The certificate is issued by a trusted organization, a certificate authority
(CA), and provides identification for the bearer.</p>

<p>Before using client authentication, make sure the client has a valid public key
certificate. For more information on creating and using public key certificates, read <a href="bnbxw.html#bnbyb">Working with Digital Certificates</a>.</p>



<a name="bncbt"></a><h4>Mutual Authentication</h4>
<a name="indexterm-2073"></a><a name="indexterm-2074"></a><p>With <b>mutual authentication</b>, the server and the client authenticate each other. Mutual authentication is
of two types:</p>


<ul><li><p>Certificate-based (see <a href="#bncbu">Figure&nbsp;40-4</a>)</p>

</li>
<li><p>User name/password-based (see <a href="#bncbv">Figure&nbsp;40-5</a>)</p>

</li></ul>
<p><a name="indexterm-2075"></a>When using certificate-based mutual authentication, the following actions occur.</p>


<ol><li><p>A client requests access to a protected resource.</p>

</li>
<li><p>The web server presents its certificate to the client.</p>

</li>
<li><p>The client verifies the server&rsquo;s certificate.</p>

</li>
<li><p>If successful, the client sends its certificate to the server.</p>

</li>
<li><p>The server verifies the client&rsquo;s credentials.</p>

</li>
<li><p>If successful, the server grants access to the protected resource requested by the client.</p>

</li></ol>
<p><a href="#bncbu">Figure&nbsp;40-4</a> shows what occurs during certificate-based mutual authentication.</p>

<a name="bncbu"></a><p class="caption">Figure&nbsp;40-4 Certificate-Based Mutual Authentication</p><img src="figures/security-sslBMAWithCertificates.gif" alt="Diagram of six steps in mutual authentication with certificates"></img><p><a name="indexterm-2076"></a>In user name/password-based mutual authentication, the following actions occur.</p>


<ol><li><p>A client requests access to a protected resource.</p>

</li>
<li><p>The web server presents its certificate to the client.</p>

</li>
<li><p>The client verifies the server&rsquo;s certificate.</p>

</li>
<li><p>If successful, the client sends its user name and password to the server, which verifies the client&rsquo;s credentials.</p>

</li>
<li><p>If the verification is successful, the server grants access to the protected resource requested by the client.</p>

</li></ol>
<p><a href="#bncbv">Figure&nbsp;40-5</a> shows what occurs during user name/password-based mutual authentication.</p>

<a name="bncbv"></a><p class="caption">Figure&nbsp;40-5 User Name/Password-Based Mutual Authentication</p><img src="figures/security-sslBMlAWUsernamePassword.gif" alt="Diagram of five steps in mutual authentication with user name and password"></img>

<a name="bncbn"></a><h4>Specifying an Authentication Mechanism in the Deployment Descriptor</h4>
<a name="indexterm-2077"></a><a name="indexterm-2078"></a><a name="indexterm-2079"></a><p>To specify an authentication mechanism, use the <tt>login-config</tt> element. It can contain the
following subelements.</p>


<ul><li><p>The <tt>auth-method</tt> subelement configures the authentication mechanism for the web application. The element content must be either <tt>NONE</tt>, <tt>BASIC</tt>, <tt>DIGEST</tt>, <tt>FORM</tt>, or <tt>CLIENT-CERT</tt>. </p>

</li>
<li><p>The <tt>realm-name</tt> subelement indicates the realm name to use when the basic authentication scheme is chosen for the web application. </p>

</li>
<li><p>The <tt>form-login-config</tt> subelement specifies the login and error pages that should be used when form-based login is specified.</p>

</li></ul>

<hr><p><b>Note - </b>Another way to specify form-based authentication is to use the <tt>authenticate</tt>, <tt>login</tt>,
and <tt>logout</tt> methods of <tt>HttpServletRequest</tt>, as discussed in <a href="gjiie.html#gircj">Authenticating Users Programmatically</a>.</p>


<hr>
<p>When you try to access a web resource that is constrained by
a <tt>security-constraint</tt> element, the web container activates the authentication mechanism that has been
configured for that resource. The authentication mechanism specifies how the user will be
prompted to log in. If the <tt>login-config</tt> element is present and the <tt>auth-method</tt>
element contains a value other than <tt>NONE</tt>, the user must be authenticated to
access the resource. If you do not specify an authentication mechanism, authentication of the
user is not required.</p>

<p>The following example shows how to declare form-based authentication in your deployment descriptor:</p>

<pre>&lt;login-config>
    &lt;auth-method>FORM&lt;/auth-method>
    &lt;realm-name>file&lt;/realm-name>
    &lt;form-login-config>
        &lt;form-login-page>/login.xhtml&lt;/form-login-page>
        &lt;form-error-page>/error.xhtml&lt;/form-error-page>
    &lt;/form-login-config>
&lt;/login-config></pre><p>The login and error page locations are specified relative to the location of
the deployment descriptor. Examples of login and error pages are shown in <a href="bncbx.html#bncca">Creating the Login Form and the Error Page</a>.</p>

<p>The following example shows how to declare digest authentication in your deployment descriptor:</p>

<pre>&lt;login-config>
    &lt;auth-method>DIGEST&lt;/auth-method>
&lt;/login-config></pre><p>The following example shows how to declare client authentication in your deployment descriptor:</p>

<pre>&lt;login-config>
    &lt;auth-method>CLIENT-CERT&lt;/auth-method>
&lt;/login-config></pre>

<a name="bncav"></a><h3>Declaring Security Roles</h3>
<a name="indexterm-2080"></a><a name="indexterm-2081"></a><a name="indexterm-2082"></a><a name="indexterm-2083"></a><p>You can declare security role names used in web applications by using the
<tt>security-role</tt> element of the deployment descriptor. Use this element to list all the
security roles that you have referenced in your application.</p>

<p>The following snippet of a deployment descriptor declares the roles that will be
used in an application using the <tt>security-role</tt> element and specifies which of these
roles is authorized to access protected resources using the <tt>auth-constraint</tt> element:</p>

<pre>&lt;security-constraint>
    &lt;web-resource-collection>
        &lt;web-resource-name>Protected Area&lt;/web-resource-name>
        &lt;url-pattern>/security/protected/*&lt;/url-pattern>
        &lt;http-method>PUT&lt;/http-method>
        &lt;http-method>DELETE&lt;/http-method>
        &lt;http-method>GET&lt;/http-method>
        &lt;http-method>POST&lt;/http-method>
    &lt;/web-resource-collection>
    &lt;auth-constraint>
        &lt;role-name>manager&lt;/role-name>
    &lt;/auth-constraint>
&lt;/security-constraint>

 &lt;!-- Security roles used by this web application -->
&lt;security-role>
    &lt;role-name>manager&lt;/role-name>
&lt;/security-role>
&lt;security-role>
    &lt;role-name>employee&lt;/role-name>
&lt;/security-role></pre><p>In this example, the <tt>security-role</tt> element lists all the security roles used in
the application: <tt>manager</tt> and <tt>employee</tt>. This enables the deployer to map all
the roles defined in the application to users and groups defined on the
GlassFish Server.</p>

<p>The <tt>auth-constraint</tt> element specifies the role, <tt>manager</tt>, that can access the HTTP
methods <tt>PUT</tt>, <tt>DELETE</tt>, <tt>GET</tt>, <tt>POST</tt> located in the directory specified by the <tt>url-pattern</tt>
element (<tt>/jsp/security/protected/*</tt>).</p>

<p>The <tt>@ServletSecurity</tt> annotation cannot be used in this situation because its constraints apply
to all URL patterns specified by the <tt>@WebServlet</tt> annotation.</p>


         </div>
         <div class="navigation">
             <a href="bncat.html"><img src="graphics/leftButton.gif" border="0" alt="Previous" title="Previous"></a>
             <a href="p1.html"><img src="graphics/upButton.gif" border="0" alt="Contents" title="Contents"></a>
             <a href="gjiie.html"><img src="graphics/rightButton.gif" border="0" alt="Next" title="Next"></a>
         </div>

         <div class="copyright">
      	    <p>Copyright &copy; 2011, Oracle and/or its affiliates. All rights reserved. <a href="docinfo.html">Legal Notices</a></p>
      	 </div>

      </td>
   </tr>
</tbody>
</table>
</body>
</html>

